home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 15 / CU Amiga Magazine's Super CD-ROM 15 (1997)(EMAP Images)(GB)[!][issue 1997-10].iso / CUCD / Graphics / Ghostscript / source / imain.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-07-03  |  9.6 KB  |  267 lines
  1. /* Copyright (C) 1995, 1996 Aladdin Enterprises.  All rights reserved.
  2.   
  3.   This file is part of Aladdin Ghostscript.
  4.   
  5.   Aladdin Ghostscript is distributed with NO WARRANTY OF ANY KIND.  No author
  6.   or distributor accepts any responsibility for the consequences of using it,
  7.   or for whether it serves any particular purpose or works at all, unless he
  8.   or she says so in writing.  Refer to the Aladdin Ghostscript Free Public
  9.   License (the "License") for full details.
  10.   
  11.   Every copy of Aladdin Ghostscript must include a copy of the License,
  12.   normally in a plain ASCII text file named PUBLIC.  The License grants you
  13.   the right to copy, modify and redistribute Aladdin Ghostscript, but only
  14.   under certain conditions described in the License.  Among other things, the
  15.   License requires that the copyright notice and this notice be preserved on
  16.   all copies.
  17. */
  18.  
  19. /* imain.h */
  20. /* Interface to imain.c */
  21. /* Requires <stdio.h>, stdpre.h, gsmemory.h, gstypes.h, iref.h */
  22.  
  23. #ifndef imain_INCLUDED
  24. #  define imain_INCLUDED
  25.  
  26. #include "gsexit.h"            /* exported by imain.c */
  27.  
  28. /*
  29.  * This file defines the intended API between client front ends
  30.  * (such as imainarg.c, the command-line-driven front end)
  31.  * and imain.c, which provides top-level control of the interpreter.
  32.  */
  33.  
  34. /* ================ Types ================ */
  35.  
  36. /*
  37.  * Currently, the interpreter has a lot of static variables, but
  38.  * eventually it will have none, so that clients will be able to make
  39.  * multiple instances of it.  In anticipation of this, many of the
  40.  * top-level API calls take an interpreter instance (gs_main_instance *)
  41.  * as their first argument.
  42.  */
  43. #ifndef gs_main_instance_DEFINED
  44. #  define gs_main_instance_DEFINED
  45. typedef struct gs_main_instance_s gs_main_instance;
  46. #endif
  47.  
  48. /* ================ Exported procedures from imain.c ================ */
  49.  
  50. /* ---------------- Instance creation ---------------- */
  51.  
  52. /*
  53.  * As noted above, multiple instances are not supported yet:
  54.  */
  55. /*gs_main_instance *gs_main_alloc_instance(P1(gs_memory_t *));*/
  56. /*
  57.  * Instead, we provide only a default instance:
  58.  */
  59. gs_main_instance *gs_main_instance_default(P0());
  60.  
  61. /* ---------------- Initialization ---------------- */
  62.  
  63. /*
  64.  * The interpreter requires three initialization steps, called init0,
  65.  * init1, and init2.  These steps must be done in that order, but
  66.  * init1 may be omitted.
  67.  */
  68.  
  69. /*
  70.  * Since gsio.h (which is included in many other header files)
  71.  * redefines stdin/out/err, callers need a way to get the "real"
  72.  * stdio files to pass to init0 if they wish to do so.
  73.  */
  74. void gs_get_real_stdio(P1(FILE *stdfiles[3]));
  75.  
  76. /*
  77.  * init0 records the files to be used for stdio, and initializes the
  78.  * graphics library, the file search paths, and other instance data.
  79.  */
  80. void gs_main_init0(P5(gs_main_instance *minst, FILE *in, FILE *out, FILE *err,
  81.               int max_lib_paths));
  82.  
  83. /*
  84.  * init1 initializes the memory manager and other internal data
  85.  * structures such as the name table, the token scanner tables,
  86.  * dictionaries such as systemdict, and the interpreter stacks.
  87.  */
  88. void gs_main_init1(P1(gs_main_instance *minst));
  89.  
  90. /*
  91.  * init2 finishes preparing the interpreter for use by running
  92.  * initialization files with PostScript procedure definitions.
  93.  */
  94. void gs_main_init2(P1(gs_main_instance *minst));
  95.  
  96. /*
  97.  * The runlibfile operator uses a search path, as described in
  98.  * use.doc, for looking up file names.  Each interpreter instance has
  99.  * its own search path.  The following call adds a directory or set of
  100.  * directories to the search path; it is equivalent to the -I command
  101.  * line switch.  It may be called any time after init0.
  102.  */
  103. void gs_main_add_lib_path(P2(gs_main_instance *minst, const char *path));
  104. /*
  105.  * Under certain internal conditions, the search path may temporarily
  106.  * be in an inconsistent state; gs_main_set_lib_paths takes care of
  107.  * this.  Clients should never need to call this procedure, and
  108.  * eventually it may be removed.
  109.  */
  110. void gs_main_set_lib_paths(P1(gs_main_instance *minst));
  111.  
  112. /*
  113.  * Open a PostScript file using the search path.  Clients should
  114.  * never need to call this procedure, since gs_main_run_file opens the
  115.  * file itself, and eventually the procedure may be removed.
  116.  */
  117. int gs_main_lib_open(P3(gs_main_instance *minst, const char *fname,
  118.             ref *pfile));
  119.  
  120. /*
  121.  * Here we summarize the C API calls that correspond to some of the
  122.  * most common command line switches documented in use.doc, to help
  123.  * clients who are familiar with the command line and are starting to
  124.  * use the API.
  125.  *
  126.  *    -d/D, -s/S (for setting device parameters like OutputFile)
  127.  *        Use the C API for device parameters documented near the
  128.  *        end of gsparam.h.
  129.  *
  130.  *    -d/D (for setting Boolean parameters like NOPAUSE)
  131.  *        { ref vtrue;
  132.  *          make_true(&vtrue);
  133.  *          dict_put_string(systemdict, "NOPAUSE", &vtrue);
  134.  *        }
  135.  *    -I
  136.  *        Use gs_main_add_lib_path, documented above.
  137.  *
  138.  *    -A, -A-
  139.  *        Set gs_debug['@'] = 1 or 0 respectively.
  140.  *    -E, -E-
  141.  *        Set gs_debug['#'] = 1 or 0 respectively.
  142.  *    -Z..., -Z-...
  143.  *        Set gs_debug[c] = 1 or 0 respectively for each character
  144.  *        c in the string.
  145.  */
  146.  
  147. /* ---------------- Execution ---------------- */
  148.  
  149. /*
  150.  * After initializing the interpreter, clients may pass it files or
  151.  * strings to be interpreted.  There are four ways to do this:
  152.  *    - Pass a file name (gs_main_run_file);
  153.  *    - Pass a C string (gs_main_run_string);
  154.  *    - Pass a string defined by pointer and length
  155.  *        (gs_main_run_string_with_length);
  156.  *    - Pass strings piece-by-piece
  157.  *        (gs_main_run_string_begin/continue/end).
  158.  *
  159.  * The value returned by the first three of these calls is
  160.  * 0 if the interpreter ran to completion, e_Quit for a normal quit,
  161.  * or e_Fatal for a non-zero quit or a fatal error.
  162.  * e_Fatal stores the exit code in the third argument.
  163.  * The str argument of gs_main_run_string[_with_length] must be allocated
  164.  * in non-garbage-collectable space (e.g., by malloc or gs_malloc,
  165.  * or statically).
  166.  */
  167. int gs_main_run_file(P5(gs_main_instance *minst,
  168.             const char *fname,
  169.             int user_errors, int *pexit_code,
  170.             ref *perror_object));
  171. int gs_main_run_string(P5(gs_main_instance *minst,
  172.               const char *str,
  173.               int user_errors, int *pexit_code,
  174.               ref *perror_object));
  175. int gs_main_run_string_with_length(P6(gs_main_instance *minst,
  176.                       const char *str, uint length,
  177.                       int user_errors, int *pexit_code,
  178.                       ref *perror_object));
  179.  
  180. /*
  181.  * Open the file for gs_main_run_file.  This is an internal routine
  182.  * that is only exported for some special clients.
  183.  */
  184. int gs_main_run_file_open(P3(gs_main_instance *minst,
  185.                  const char *file_name, ref *pfref));
  186.  
  187. /*
  188.  * The next 3 procedures provide for feeding input to the interpreter
  189.  * in arbitrary chunks, unlike run_string, which requires that each string
  190.  * be a properly formed PostScript program fragment.  To use them:
  191.  *    Call run_string_begin.
  192.  *    Call run_string_continue as many times as desired,
  193.  *      stopping if it returns anything other than e_NeedInput.
  194.  *    If run_string_continue didn't indicate an error or a quit
  195.  *      (i.e., a return value other than e_NeedInput), call run_string_end
  196.  *      to provide an EOF indication.
  197.  * Note that run_string_continue takes a pointer and a length, like
  198.  * run_string_with_length.
  199.  */
  200. int gs_main_run_string_begin(P4(gs_main_instance *minst, int user_errors,
  201.                 int *pexit_code, ref *perror_object));
  202. int gs_main_run_string_continue(P6(gs_main_instance *minst,
  203.                    const char *str, uint length,
  204.                    int user_errors, int *pexit_code,
  205.                    ref *perror_object));
  206. int gs_main_run_string_end(P4(gs_main_instance *minst, int user_errors,
  207.                   int *pexit_code, ref *perror_object));
  208.  
  209. /* ---------------- Operand stack access ---------------- */
  210.  
  211. /*
  212.  * The following procedures are not used in normal operation;
  213.  * they exist only to allow clients driving the interpreter through the
  214.  * gs_main_run_xxx procedures to push parameters quickly and to get results
  215.  * back.  The push procedures return 0, e_stackoverflow, or e_VMerror;
  216.  * the pop procedures return 0, e_stackunderflow, or e_typecheck.
  217.  *
  218.  * Procedures to push values on the operand stack:
  219.  */
  220. int gs_push_boolean(P2(gs_main_instance *minst, bool value));
  221. int gs_push_integer(P2(gs_main_instance *minst, long value));
  222. int gs_push_real(P2(gs_main_instance *minst, floatp value));
  223. int gs_push_string(P4(gs_main_instance *minst, byte *chars, uint length,
  224.               bool read_only));
  225. /*
  226.  * Procedures to pop values from the operand stack:
  227.  */
  228. int gs_pop_boolean(P2(gs_main_instance *minst, bool *result));
  229. int gs_pop_integer(P2(gs_main_instance *minst, long *result));
  230. int gs_pop_real(P2(gs_main_instance *minst, float *result));
  231. /* gs_pop_string returns 1 if the string is read-only. */
  232. int gs_pop_string(P2(gs_main_instance *minst, gs_string *result));
  233.  
  234. /* ---------------- Debugging ---------------- */
  235.  
  236. /*
  237.  * Print an error mesage including the error code, error object (if any),
  238.  * and operand and execution stacks in hex.  Clients will probably
  239.  * never call this.
  240.  */
  241. void gs_debug_dump_stack(P2(int code, ref *perror_object));
  242.  
  243. /* ---------------- Termination ---------------- */
  244.  
  245. /*
  246.  * Terminate the interpreter by closing all devices and releasing all
  247.  * allocated memory.  Currently, because of some technical problems
  248.  * with statically initialized data, it is not possible to reinitialize
  249.  * the interpreter after terminating it; we plan to fix this as soon as
  250.  * possible.
  251.  *
  252.  * Note that calling gs_exit (defined in gsexit.h) automatically calls
  253.  * gs_main_finit for the default instance.
  254.  */
  255. void gs_main_finit(P3(gs_main_instance *minst, int exit_status, int code));
  256.  
  257. /* ================ Other exported procedures ================ */
  258.  
  259. /*
  260.  * Define an internal interface to the interpreter.  Clients do not
  261.  * normally use this.
  262.  */
  263. int gs_interpret(P4(ref *pref, int user_errors, int *pexit_code,
  264.             ref *perror_object));
  265.  
  266. #endif                    /* imain_INCLUDED */
  267.